Skip to content

chore: claude and agents files for contract#135

Merged
karim-en merged 4 commits into
mainfrom
add-claude-md
Apr 9, 2026
Merged

chore: claude and agents files for contract#135
karim-en merged 4 commits into
mainfrom
add-claude-md

Conversation

@karim-en
Copy link
Copy Markdown
Collaborator

This pull request introduces a new local build target for the smart contract and adds comprehensive documentation for the BTC Light Client Contract. The most significant changes are the addition of a build-local target in the Makefile for easier development on macOS, and the inclusion of a detailed project overview and instructions in contract/CLAUDE.md.

Build system improvements:

  • Added a build-local target to the Makefile, allowing developers to build all chain variants locally with macOS-specific LLVM paths. This simplifies development and testing on Apple Silicon machines. [1] [2]

Documentation additions:

  • Added contract/CLAUDE.md, which provides a thorough overview of the BTC Light Client Contract, including supported chains, core functions, architecture, block submission flow, chain reorganization, transaction verification, and garbage collection.
  • Updated contract/AGENTS.md to reference the new CLAUDE.md documentation file.

@karim-en karim-en requested review from kiseln and olga24912 February 16, 2026 23:38
Comment thread contract/CLAUDE.md Outdated

## Core Functions

### Write Methods
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all methods are self-explanatory with an exception of gc method

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But gc is also described further down below so I would remove this section completely

Comment thread contract/CLAUDE.md Outdated

A Bitcoin SPV light client implemented as a NEAR Protocol smart contract. It verifies and stores block headers on-chain, enabling trustless verification of Bitcoin (and other UTXO chain) transactions without running a full node. Relayers can submit blocks and they are verified on-chain via proof-of-work validation, difficulty adjustment checks, and chain selection rules.

**Supported chains** (compile-time feature flags, mutually exclusive):
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mentioned below in the same document. Let's keep only one instance

Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md
Comment thread contract/CLAUDE.md Outdated
Comment thread contract/CLAUDE.md Outdated
@karim-en
Copy link
Copy Markdown
Collaborator Author

karim-en commented Apr 9, 2026

@olga24912 4414efd

  1. Line 5: Changed "A Bitcoin SPV" → "A Bitcoin/Litecoin/Dogecoin/Zcash SPV" to acknowledge all supported chains upfront
  2. Removed "Supported chains" and "Core Functions" sections (kiseln noted these are self-explanatory from code and duplicated below)
  3. Build section: Added per-chain build commands (make build-bitcoin, etc.) with their feature flags
  4. gc_threshold (line 39): Clarified it's mainchain-only, explained when GC triggers (automatically in submit_blocks() + manual), and that fork blocks are unaffected
  5. Reorg caveat (line 60): Added warning about GC'd blocks causing PrevBlockNotFound panic during reorg — GC depth must be conservative
  6. Garbage Collection section (line 71): Clarified mainchain-only scope and explained batch_size bounds gas usage
  7. Feature flags (line 79): Added explicit flag syntax --no-default-features --features ""
  8. Zcash (line 86): Fixed averaging window from 45 → 17 blocks (verified from pow_averaging_window: 17 in [network.rs]

@karim-en karim-en merged commit 89518c9 into main Apr 9, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants